Skip to main content

Factory

note

Each integrated chain has its own factory contract. These contracts will be created by Euclid whenever an integration with a new chain occurs. You can read about the factory architecture here.

Execute Messages

List of execute messages that can be performed on the Factory contract.

Swap Request

note

The asset_in is the token being swapped from, and asset_out is the token you want to receive. Cross-chain support is built in via the cross_chain_addresses field.

function swap_request(
    CrossChainUser memory sender,
    TokenWithDenom memory asset_in,
    uint256 amount_in,
    string memory asset_out,
    uint256 min_amount_out,
    NextSwapPair[] memory swaps,
    CrossChainUserWithLimit[] memory cross_chain_addresses,
    PartnerFee memory partnerFee,
    string memory meta
) external;
{
  "swap_request": {
    "sender": {
      "chain_uid": "ethereum",
      "address": "0xabc123abc123abc123abc123abc123abc123abcd"
    },
    "asset_in": {
      "token": "usdc",
      "token_type": {
        "native": {
          "denom": "usdc"
        }
      }
    },
    "amount_in": "1000000",
    "asset_out": "dai",
    "min_amount_out": "990000",
    "swaps": [
      {
        "token_in": "usdc",
        "token_out": "weth"
      },
      {
        "token_in": "weth",
        "token_out": "dai"
      }
    ],
    "cross_chain_addresses": [
      {
        "user": {
          "chain_uid": "arbitrum",
          "address": "0xdef456def456def456def456def456def456abcd"
        },
        "limit": "800000"
      }
    ],
    "partner_fee": {
      "partner_fee_bps": 25,
      "recipient": "0xgkhj33..."
    }
  }
}
FieldTypeDescription
senderCrossChainUserOptional user to execute the swap on behalf of. Typically, you do not need to specify a sender field. Users send tokens directly with their transaction. However, in cross-chain transactions involving IBC (where asynchronous behavior happens), external contracts may want to trigger swaps and have vouchers minted directly to a user instead of the contract itself. In these cases, setting sender allows the final minted vouchers to be credited properly.
asset_inTokenWithDenomThe token being used as input for the swap.
amount_inuint256Amount of asset_in to swap. For native assets, this is overridden by msg.value.
asset_outstringTarget token the user wants to receive.
min_amount_outuint256Minimum amount of the output asset for the swap to be considered a success. Used to specify maximum slippage accepted.
swapsNextSwapPair[]The different swaps to get from asset_in to asset_out. This could be a direct swap or multiple swaps. For example, if swapping from token A to B, the swaps can be A -> B directly, or A -> C then C-> D then D->B. Usually the most efficient route is used.
cross_chain_addressesCrossChainUserWithLimit[]A set of addresses to specify where the asset_out should be released. The first element specified in the vector has highest priority and so on. User specifies a limit for each provided address which indicates the amount of funds that should be released to that address. In case there are any leftover funds, they are added to the user's virtual balance for the address that initiated the swap. If limit is not specified, then the maximum amount is taken.
partner_feePartnerFeeOptional partner fee information for swaps. The maximum fee that can be set is 30 (0.3%).
metastringOptional metadata field for tracking or sequencing.

With the following structs:

struct NextSwapPair {
    string token_in;
    string token_out;
}

// The percentage of the fee for the platform. Specified in basis points (bps)
// Example: 1 = 0.01%, 30 = 0.3%, 10000 = 100%
struct PartnerFee {
    uint64 partner_fee_bps;    // Max 30 (0.3%)
    address recipient;         // Address to receive the fee
}
StructFieldTypeDescription
NextSwapPairtoken_instringThe input token in the swap segment.
token_outstringThe output token in the swap segment.
PartnerFeepartner_fee_bpsuint64Fee percentage in basis points (max 30 = 0.3%).
recipientaddressAddress that receives the partner/referral fee.

Deposit Token

tip

Used to deposit tokens into the protocol and receive voucher tokens in return. Supports native and smart tokens.

function depositToken(
  TokenWithDenom memory asset_in,
  uint256 amount_in,
  CrossChainUser memory recipientOpt
) external;
{
  "deposit_token": {
    "asset_in": {
      "token": "usdc",
      "token_type": {
        "native": {
          "denom": "usdc"
        }
      }
    },
    "amount_in": "500000",
    "recipient": {
      "chain_uid": "amoy",
      "address": "0xfeed123feed123feed123feed123feed123abcd"
    }
  }
}
FieldTypeDescription
asset_inTokenWithDenomThe asset being exchanged into vouchers.
amount_inuint256Amount of the token to deposit.
recipientCrossChainUserOptional recipient for the voucher tokens. Defaults to the sender if omitted.

Withdraw Virtual Balance

note

This message lets users withdraw voucher tokens and release them to one or more cross-chain addresses.

function withdrawVirtualBalance(
  string memory token,
  uint128 amount,
  CrossChainUserWithLimit[] memory cross_chain_addresses
) external;
{
  "withdraw_virtual_balance": {
    "token": "dai",
    "amount": "250000",
    "cross_chain_addresses": [
      {
        "user": {
          "chain_uid": "ethereum",
          "address": "0x00112233445566778899aabbccddeeff00112233"
        },
        "limit": "200000"
      },
      {
        "user": {
          "chain_uid": "optimism",
          "address": "0x445566778899aabbccddeeff0011223344556677"
        }
      }
    ]
  }
}
FieldTypeDescription
tokenstringID of the voucher token to withdraw.
amountuint128The amount of voucher tokens to withdraw.
cross_chain_addressesCrossChainUserWithLimit[]List of destination addresses to receive the withdrawn funds.

Transfer Virtual Balance

Transfers voucher tokens from the sender’s virtual balance to another user on a specific chain.

function transferVirtualBalance(
  string memory token,
  uint256 amount,
  CrossChainUser memory recipient_address
) external;
{
  "transfer_virtual_balance": {
    "token": "dai",
    "amount": "150000",
    "recipient_address": {
      "chain_uid": "amoy",
      "address": "0xaabbccddeeff0011223344556677889900aabbcc"
    }
  }
}
FieldTypeDescription
tokenstringThe voucher token ID to transfer.
amountuint256Amount of virtual balance to transfer.
recipient_addressCrossChainUserTarget address and chain to receive the tokens.

Add Liquidity Request

Adds liquidity to a pool using a pair of tokens. User receives LP tokens representing their share in the pool. Supports native and smart tokens.

function addLiquidityRequest(
  PairWithDenomAndAmount memory pair_info,
  uint64 slippage_tolerance_bps
) external;
{
  "add_liquidity_request": {
    "pair_info": {
      "token_1": {
        "token": "usdc",
        "amount": "1000000",
        "token_type": {
          "native": {
            "denom": "usdc"
          }
        }
      },
      "token_2": {
        "token": "dai",
        "amount": "1000000",
        "token_type": {
          "smart": {
            "contract_address": "0x5f123abc123abc123abc123abc123abc123abcde"
          }
        }
      }
    },
    "slippage_tolerance_bps": 300
  }
}
FieldTypeDescription
pair_infoPairWithDenomAndAmountToken pair and amounts to add as liquidity.
slippage_tolerance_bpsuint64Max slippage tolerated in basis points (e.g., 300 = 3%).

Remove Liquidity Request

Removes liquidity from a pool and sends the tokens to one or more cross-chain addresses based on the user's allocation preferences.

function removeLiquidityRequest(
  Pair memory pair,
  uint256 lp_allocation,
  CrossChainUserWithLimit[] memory cross_chain_addresses
) external;
{
  "remove_liquidity_request": {
    "pair": {
      "token_1": "usdc",
      "token_2": "dai"
    },
    "lp_allocation": "100000000000",
    "cross_chain_addresses": [
      {
        "user": {
          "chain_uid": "amoy",
          "address": "0xfeed123feed123feed123feed123feed123abcd"
        },
        "limit": "500000"
      },
      {
        "user": {
          "chain_uid": "arbitrum",
          "address": "0xdef456def456def456def456def456def456abcd"
        }
      }
    ]
  }
}
FieldTypeDescription
pairPairThe token pair for the pool you want to remove liquidity from.
lp_allocationuint256Amount of LP tokens to redeem.
cross_chain_addressesCrossChainUserWithLimit[]Where to send the redeemed tokens. First entry has the highest priority.

Request Pool Creation

Sends a request to create a new liquidity pool for a given token pair. The user defines the pool configuration and LP token metadata.

function request_pool_creation(
  PairWithDenomAndAmount memory pair,
  uint64 slippage_tolerance_bps,
  string memory lp_token_name,
  string memory lp_token_symbol,
  uint8 lp_token_decimal
) external;
{
  "request_pool_creation": {
    "pair": {
      "token_1": {
        "token": "usdc",
        "amount": "500000",
        "token_type": {
          "native": {
            "denom": "usdc"
          }
        }
      },
      "token_2": {
        "token": "dai",
        "amount": "500000",
        "token_type": {
          "smart": {
            "contract_address": "0x9876543210abcdef9876543210abcdef98765432"
          }
        }
      }
    },
    "slippage_tolerance_bps": 200,
    "lp_token_name": "USDC-DAI Pool Token",
    "lp_token_symbol": "USDCDAI-LP",
    "lp_token_decimal": 18
  }
}
FieldTypeDescription
pairPairWithDenomAndAmountToken pair and amounts used to initialize the pool.
slippage_tolerance_bpsuint64Max slippage allowed when creating the pool (in basis points).
lp_token_namestringFull name of the LP token.
lp_token_symbolstringSymbol (ticker) of the LP token.
lp_token_decimaluint8Number of decimals used by the LP token.

Query Messages

List of queries that can be performed on the Factory contract.

Get State

Queries the configuration and current status of the Factory contract.

Query Call

function getState() external view returns (State memory);
{
  "get_state": {}
}

Response

struct State {
    string chain_uid;
    address router;
    address admin;
    uint256 escrow_code_id;
    uint256 voucher_token_code_id;
    bool is_native;
    DenomFees partner_fees_collected;
}

struct DenomFees {
    string[] denoms;
    uint256[] amounts;
}
FieldTypeDescription
chain_uidstringUnique chain ID (e.g., "amoy", "ethereum").
routeraddressAddress of the router contract.
adminaddressAddress of the factory admin.
escrow_code_iduint256Code ID for escrow contract deployment.
voucher_token_code_iduint256Code ID for voucher token contracts.
is_nativeboolWhether the factory is native to this chain.
partner_fees_collectedDenomFeesFee totals per denom collected from partner fees.

Get All Tokens

Returns a list of all token IDs registered in the factory.

Query Call

function getAllTokens() external view returns (string[] memory);
{
  "get_all_tokens": {}
}

Response

string[] tokens;
FieldTypeDescription
tokensstring[]List of registered token IDs.

Get Partner Fees Collected

Returns the total amount of partner fees collected by the protocol, grouped by token denomination.

Query Call

function getPartnerFeesCollected() external view returns (DenomFees memory);
{
  "get_partner_fees_collected": {}
}

Response

struct DenomFees {
    string[] denoms;
    uint256[] amounts;
}
FieldTypeDescription
denomsstring[]Array of token denoms (e.g., usdc, dai).
amountsuint256[]Total amount collected for each corresponding denom.

Get LP Token

Returns the address of the LP (liquidity provider) token for the specified VLP contract.

Query Call

function getLPToken(address vlp) external view returns (address);
{
  "get_l_p_token": {
    "vlp": "nibi..."
  }
}

Input Parameters

FieldTypeDescription
vlpaddressThe address of the liquidity pool (VLP).

Response

address lp_token_address;
FieldTypeDescription
lp_token_addressaddressThe ERC20 contract address of the LP token.

Get VLP

Returns the VLP contract address for a given token pair.

Query Call

function getVlp(Pair memory pair) external view returns (address);
{
  "get_vlp": {
    "pair": {
      "token_1": "usdc",
      "token_2": "dai"
    }
  }
}

Input Parameters

FieldTypeDescription
token_1stringID of the first token in the pair.
token_2stringID of the second token in the pair.

Response

address vlp_address;
FieldTypeDescription
vlp_addressaddressAddress of the VLP contract for the given pair.

Get VLP

Returns the VLP contract address for a given token pair.

Query Call

function getVlp(Pair memory pair) external view returns (address);
{
  "get_vlp": {
    "pair": {
      "token_1": "usdc",
      "token_2": "dai"
    }
  }
}

Input Parameters

FieldTypeDescription
token_1stringID of the first token in the pair.
token_2stringID of the second token in the pair.

Response

address vlp_address;
FieldTypeDescription
vlp_addressaddressAddress of the VLP contract for the given pair.

Get All Pools

Returns all registered liquidity pools and their associated token pairs.

Query Call

function getAllPools() external view returns (PoolVlpResponse[] memory);

struct PoolVlpResponse {
    Pair pair;
    address vlp;
}
{
  "get_all_pools": {}
}

Response

struct PoolVlpResponse {
    Pair pair;
    address vlp;
}

struct Pair {
    string token_1;
    string token_2;
}
FieldTypeDescription
pair.token_1stringFirst token in the liquidity pair.
pair.token_2stringSecond token in the liquidity pair.
vlpaddressThe address of the corresponding VLP contract.

Get Escrow

Returns the escrow contract address and token types for a given token ID.

Query Call

function getEscrow(string memory token_id) external view returns (EscrowResponse memory);

struct EscrowResponse {
    address escrow_address;
    TokenType[] token_types;
}
{
  "get_escrow": {
    "token_id": "usdc"
  }
}

Input Parameters

FieldTypeDescription
token_idstringThe token ID to look up escrow for.

Response

struct EscrowResponse {
    address escrow_address;
    TokenType[] token_types;
}
FieldTypeDescription
escrow_addressaddressAddress of the escrow contract (if any).
token_typesTokenType[]Supported token types backing this token ID.